Bitmap Geometries (IM: XG)

Inside Macintosh: QuickDraw GX Graphics /: Chapter 5 - Bitmap Shapes / About Bitmap Shapes

Bitmap Geometries
The geometry of a bitmap contains eight fields:

The pixel image--a pointer to a two-dimensional array of pixel values. Each pixel value represents the color of one pixel of the bitmap.
The bitmap width--the number of pixels in each row of the bitmap.
The bitmap height--the number of pixels in each column of the bitmap.
The pixel size--the number of bits required to represent the color information for each pixel of the bitmap.
The bytes per row--the number of bytes of the pixel image that correspond to each row of the bitmap.
The bitmap color space--or the color space that determines how QuickDraw GX translates the bitmap's pixel values into colors. If the bitmap has any color space except indexed space, each pixel value in the pixel image represents a color specification in this color space. If the bitmap has an indexed color space, each pixel value is interpreted using the bitmap color set.
The bitmap color set--the optional array of color values associated with the bitmap. If the bitmap uses a color set (also called an indexed color space), each pixel value in the bitmap's pixel image represents an index into this color set.
The bitmap color profile--the color-matching information that you can specify for the device on which the bitmap was created.
The bitmap position--the position of the upper-left corner of the bitmap. The actual position of the bitmap when drawn may differ depending on the information in the bitmap's transform object.

QuickDraw GX provides the bitmap data type which you can use to create bitmap geometries. The bitmap data type has a field corresponding to every field of a bitmap geometry except the bitmap position. You must set and determine the bitmap position programmatically.
QuickDraw GX enforces a few restrictions on the values of these geometry fields. For example, the pixel size of the bitmap must be a power of 2 (from 1 to 32), and it must correspond to the pixel size implicit in the bitmap color space.
The bytes per row of the bitmap must be a multiple of 2. This requirement allows for faster bitmap manipulation.

Note
Although the Macintosh platform accepts any even number of bytes per row, you might want to use a multiple of 4 bytes per row in your bitmaps to promote cross-platform compatibility.
Sometimes you must pad a pixel image with extra bits to get an even number of bytes per row. For example, Figure 5-2 shows a small, black-and-white (1 bit per pixel) bitmap with a bitmap width of 10. The smallest number of bytes per row into which 10 bits fit is 2, so the number of bytes per row for this bitmap is 2. Although the six extra bits at the end of each row of the pixel image have values, they do not appear as pixels in the bitmap when it is drawn.
Figure 5-2 A black-and-white bitmap geometry

All QuickDraw GX bitmaps are actually color bitmaps. A black-and-white bitmap is simply a color bitmap with a color set containing only two colors--black and white.
Figure 5-3 shows another bitmap. In this example, the pixel size is 2; each pixel is represented by 2 bits. Since no color space has an implicit pixel size of 2, this bitmap uses a color set instead of a color space. In this example, the color set contains four shades of gray (although it could contain any four colors); each pixel value in the pixel image is an index into this color set. Since the bitmap width is 5 pixels and the pixel size is 2 bits per pixel, at least 10 bits are required to represent each row of the pixel image. The smallest number of bytes per row that contains 10 bits is 2 bytes, so each row of the bitmap has 16 bits total. The last 6 bits are ignored by QuickDraw GX.
Figure 5-3 A grayscale bitmap geometry

QuickDraw GX allows you to store a bitmap's pixel image in one of three locations:

You can allocate memory for the pixel image yourself. In this case, you provide QuickDraw GX with a pointer to the memory containing your pixel image. The section "Creating and Drawing Bitmaps" beginning on page 5-15 gives examples of allocating memory for a pixel image yourself and incorporating the pixel image into a bitmap shape.
You can request that QuickDraw GX allocate the memory for you. In this case, you must use QuickDraw GX functions to draw into the bitmap and to edit it. If you want to edit the pixel image directly, you can use other QuickDraw GX functions to lock the image in memory and to request a pointer to it. However, if QuickDraw GX is storing the pixel image on an accelerator card, your application might not be able to edit the pixel image directly. The section "Creating Bitmaps Offscreen" beginning on page 5-45 gives an example of requesting that QuickDraw GX allocate memory for your pixel image.
You can associate the bitmap with a disk-based pixel image--a pixel image stored in a disk file. In this case, you can use QuickDraw GX functions to read and draw the bitmap, but you cannot use QuickDraw GX functions to edit the bitmap. You must edit the bitmap directly using file-manipulation functions. The section "Creating Bitmaps With Disk-Based Pixel Images" beginning on page 5-44 shows how you can create a bitmap that uses a disk-based pixel image.